RobertIndie commented on code in PR #23075: URL: https://github.com/apache/pulsar/pull/23075#discussion_r1696765905
########## pip/pip-368.md: ########## @@ -0,0 +1,148 @@ +# PIP-368: Support client properties for the lookup + +# Background knowledge + +## How Pulsar Lookup Works + +Before producing or consuming messages, a Pulsar client must first find the broker responsible for the topic. This +happens through the lookup service. The client sends a `CommandLookupTopic` request with the topic name to the lookup +service, which then returns the responsible broker. The client then interacts with this broker to produce or consume +messages. + +On the broker side, users can customize lookup logic by setting a custom load manager in the `loadManagerClassName` +configuration. + +# Motivation + +Currently, the lookup process uses only the topic name as its parameter. However, to enhance this process, it's +beneficial for clients to provide additional information. This could be done by introducing the `properties` field in +the client configuration. The client can then send these properties to the broker during the lookup process. + +Here is a scenario for using the client properties for the lookup: +Assuming there are two brokers that broker-0 configures the "rack" property with "A" and broker-1 configures the "rack" +property with "B". By using the lookup properties, clients can supply rack information during the lookup, enabling the +broker to identify and connect them to the nearest broker within the same rack. If a client that configures the "rack" +property with "A" connects to a lookup broker, the customized load manager can determine broker-0 as the owner broker +since the broker and the client have the same rack property. + +# Goals + +## In Scope + +- Enable clients to send additional lookup information to brokers during the lookup. + +## Out of Scope + +None + +# High Level Design + +Add new configuration `properties` to the client. While looking up the broker, the client will send the properties to +the broker through `CommandLookupTopic` request. +The `properties` will be added to the `LookupOptions`. The Load Manager implementation can retrieve the `properties` +through `LookupOptions` to make a better decision on which broker to return. +The properties are used only when the protocol is the binary protocol, starting with `pulsar://` or `pulsar+ssl://`, or +if the `loadManagerClassName` in the broker is a class that implements the `ExtensibleLoadManager` interface. + +# Detailed Design + +## Design & Implementation Details + +## Public-facing Changes + +### Configuration + +Add new configuration `properties` to the `ClientBuilder`. + +```java +/** + * Set the properties used for topic lookup. + * <p> + * When the broker performs topic lookup, these properties will be taken into consideration in a customized load + * manager. + * <p> + * Note: The properties are only used in topic lookup when: + * - The protocol is binary protocol, i.e. the service URL starts with "pulsar://" or "pulsar+ssl://" + * - The `loadManagerClassName` config in broker is a class that implements the `ExtensibleLoadManager` interface + */ +ClientBuilder properties(Map<String, String> properties); +``` + +### Binary protocol + +Add `properties` field to the `CommandLookupTopic`. Now the `CommandLookupTopic will look like: Review Comment: Thanks. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
