merge upstream main into docs-23836-client-download-links

Author: singhvishalkr

.github/workflows/ci-build-site.yml

@@ -31,6 +31,8 @@ jobs:
     name: Build and publish pulsar website-next
     runs-on: ubuntu-latest
     timeout-minutes: 600
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v6
         with:
@@ -39,7 +41,6 @@ jobs:
         with:
           ref: 'asf-site-next'
           path: tmp/asf-site-next
-          token: ${{ secrets.PULSARBOT_TOKEN }}
       - name: Install poetry
         run: pipx install poetry
       - uses: actions/setup-python@v6
@@ -53,6 +54,8 @@ jobs:
       - run: corepack enable
       - name: Update generated docs
         working-directory: tools/pytools
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
         run: |
           poetry install
           poetry run bin/site-publisher.py --site-path=$GITHUB_WORKSPACE/tmp/asf-site-next

client-libraries/consumers.md

@@ -79,11 +79,11 @@ Create a new consumer and subscribe with the `Exclusive` subscription type.
 <TabItem value="Java">
 
 ```java
-Consumer consumer = client.newConsumer()
+Consumer<byte[]> consumer = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscriptionType(SubscriptionType.Exclusive)
-        .subscribe()
+        .subscribe();
 ```
 
   </TabItem>
@@ -117,18 +117,18 @@ Create new consumers and subscribe with the `Failover` subscription type.
 <TabItem value="Java">
 
 ```java
-Consumer consumer1 = client.newConsumer()
+Consumer<byte[]> consumer1 = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscriptionType(SubscriptionType.Failover)
-        .subscribe()
-Consumer consumer2 = client.newConsumer()
+        .subscribe();
+Consumer<byte[]> consumer2 = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscriptionType(SubscriptionType.Failover)
-        .subscribe()
-//conumser1 is the active consumer, consumer2 is the standby consumer.
-//consumer1 receives 5 messages and then crashes, consumer2 takes over as an  active consumer.
+        .subscribe();
+//consumer1 is the active consumer, consumer2 is the standby consumer.
+//consumer1 receives 5 messages and then crashes, consumer2 takes over as an active consumer.
 ```
 
   </TabItem>
@@ -184,17 +184,17 @@ Create new consumers and subscribe with `Shared` subscription type.
 <TabItem value="Java">
 
 ```java
-Consumer consumer1 = client.newConsumer()
+Consumer<byte[]> consumer1 = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscriptionType(SubscriptionType.Shared)
-        .subscribe()
+        .subscribe();
 
-Consumer consumer2 = client.newConsumer()
+Consumer<byte[]> consumer2 = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscriptionType(SubscriptionType.Shared)
-        .subscribe()
+        .subscribe();
 //Both consumer1 and consumer2 are active consumers.
 ```
 
@@ -253,17 +253,17 @@ When using Key_Shared subscriptions, producers **must** either **disable batchin
 <TabItem value="Java">
 
 ```java
-Consumer consumer1 = client.newConsumer()
+Consumer<byte[]> consumer1 = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscriptionType(SubscriptionType.Key_Shared)
-        .subscribe()
+        .subscribe();
 
-Consumer consumer2 = client.newConsumer()
+Consumer<byte[]> consumer2 = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscriptionType(SubscriptionType.Key_Shared)
-        .subscribe()
+        .subscribe();
 //Both consumer1 and consumer2 are active consumers.
 ```
 

client-libraries/java-use.md

@@ -54,7 +54,7 @@ In Pulsar, consumers subscribe to topics and handle messages that producers publ
 Once you've instantiated a [PulsarClient](@pulsar:javadoc:client@/org/apache/pulsar/client/api/PulsarClient) object, you can create a [Consumer](@pulsar:javadoc:client@/org/apache/pulsar/client/api/Consumer) by specifying a [topic](pathname:///docs/reference-terminology#topic) and a [subscription](pathname:///docs/concepts-messaging#subscription-types).
 
 ```java
-Consumer consumer = client.newConsumer()
+Consumer<byte[]> consumer = client.newConsumer()
         .topic("my-topic")
         .subscriptionName("my-subscription")
         .subscribe();
@@ -65,7 +65,7 @@ The `subscribe` method will auto-subscribe the consumer to the specified topic a
 ```java
 while (true) {
   // Wait for a message
-  Message msg = consumer.receive();
+  Message<byte[]> msg = consumer.receive();
 
   try {
       // Do something with the message
@@ -83,16 +83,16 @@ while (true) {
 If you don't want to block your main thread but constantly listen for new messages, consider using a `MessageListener`. The `MessageListener` will use a thread pool inside the PulsarClient. You can set the number of threads to use for message listeners in the ClientBuilder.
 
 ```java
-MessageListener myMessageListener = (consumer, msg) -> {
+MessageListener<byte[]> myMessageListener = (consumer, msg) -> {
   try {
       System.out.println("Message received: " + new String(msg.getData()));
       consumer.acknowledge(msg);
   } catch (Exception e) {
       consumer.negativeAcknowledge(msg);
   }
-}
+};
 
-Consumer consumer = client.newConsumer()
+Consumer<byte[]> consumer = client.newConsumer()
      .topic("my-topic")
      .subscriptionName("my-subscription")
      .messageListener(myMessageListener)
@@ -108,13 +108,13 @@ The following is an example.
 ```java
 byte[] msgIdBytes = // Some message ID byte array
 MessageId id = MessageId.fromByteArray(msgIdBytes);
-Reader reader = pulsarClient.newReader()
+Reader<byte[]> reader = pulsarClient.newReader()
         .topic(topic)
         .startMessageId(id)
         .create();
 
 while (true) {
-    Message message = reader.readNext();
+    Message<byte[]> message = reader.readNext();
     // Process message
 }
 ```

client-libraries/node-configs.md

@@ -18,11 +18,16 @@ The following configurable parameters are available for Pulsar Node.js clients:
 | `ioThreads` | The number of threads to use for handling connections to Pulsar [brokers](pathname:///docs/reference-terminology#broker). | 1 |
 | `messageListenerThreads` | The number of threads used by message listeners ([consumers](#consumers) and [readers](#readers)). | 1 |
 | `concurrentLookupRequest` | The number of concurrent lookup requests that can be sent on each broker connection. Setting a maximum helps to keep from overloading brokers. You should set values over the default of 50000 only if the client needs to produce and/or subscribe to thousands of Pulsar topics. | 50000 |
-| `tlsTrustCertsFilePath` | The file path for the trusted TLS certificate. | |
+| `tlsTrustCertsFilePath` | The file path for the trusted TLS certificate. If unset, the client falls back to a `cert.pem` file bundled with the package that is seeded from the Node.js runtime's root CAs at install time. | Bundled `cert.pem` |
+| `tlsCertificateFilePath` | The file path for the client TLS certificate used for mTLS. | |
+| `tlsPrivateKeyFilePath` | The file path for the client TLS private key used for mTLS. | |
 | `tlsValidateHostname` | The boolean value of setup whether to enable TLS hostname verification. | `false` |
 | `tlsAllowInsecureConnection` | The boolean value of setup whether the Pulsar client accepts untrusted TLS certificate from broker. | `false` |
 | `statsIntervalInSeconds` | Interval between each stat info. Stats is activated with positive statsInterval. The value should be set to 1 second at least | 600 |
-| `log` | A function that is used for logging. | `console.log` |
+| `listenerName` | The listener name the client will use when connecting to the broker. Useful when [advertising multiple endpoints](pathname:///docs/concepts-multi-tenancy). | |
+| `log` | A function that is used for logging. Receives `(level, file, line, message)` arguments. | `console.log` |
+| `logLevel` | The log level for client-emitted logs. Accepts `LogLevel.DEBUG` (0), `LogLevel.INFO` (1), `LogLevel.WARN` (2), or `LogLevel.ERROR` (3). | `LogLevel.INFO` |
+| `connectionTimeoutMs` | Duration (in milliseconds) to wait for a broker connection to establish before failing. | |
 
 
 ## Producer configs

client-libraries/producers.md

@@ -411,19 +411,20 @@ The following is an example:
   values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"},{"label":"Go","value":"Go"},{"label":"Python","value":"Python"}]}>
 <TabItem value="Java">
 
-To use a custom message router, you need to provide an implementation of the [MessageRouter](@pulsar:javadoc:client@/org/apache/pulsar/client/api/MessageRouter) interface, which has just one `choosePartition` method:
+To use a custom message router, you need to provide an implementation of the [MessageRouter](@pulsar:javadoc:client@/org/apache/pulsar/client/api/MessageRouter) interface. Implement the `choosePartition(Message<?>, TopicMetadata)` method (the single-argument overload is deprecated since 1.22.0):
 
 ```java
 public interface MessageRouter extends Serializable {
-    int choosePartition(Message msg);
+    int choosePartition(Message<?> msg, TopicMetadata metadata);
 }
 ```
 
 The following router routes every message to partition 10:
 
 ```java
 public class AlwaysTenRouter implements MessageRouter {
-    public int choosePartition(Message msg) {
+    @Override
+    public int choosePartition(Message<?> msg, TopicMetadata metadata) {
         return 10;
     }
 }
@@ -627,21 +628,28 @@ To intercept messages, you can add a `ProducerInterceptor` or multiple ones when
    ```java
    Producer<byte[]> producer = client.newProducer()
         .topic(topic)
-        .intercept(new ProducerInterceptor {
-			@Override
-			boolean eligible(Message message) {
-			    return true;  // process all messages
-			}
-
-			@Override
-			Message beforeSend(Producer producer, Message message) {
-			    // user-defined processing logic
-			}
-
-			@Override
-			void onSendAcknowledgement(Producer producer, Message message, MessageId msgId, Throwable exception) {
-			    // user-defined processing logic
-			}
+        .intercept(new ProducerInterceptor() {
+            @Override
+            public void close() {
+                // release any resources held by the interceptor
+            }
+
+            @Override
+            public boolean eligible(Message<?> message) {
+                return true;  // process all messages
+            }
+
+            @Override
+            public Message<?> beforeSend(Producer<?> producer, Message<?> message) {
+                // user-defined processing logic; return the (possibly modified) message
+                return message;
+            }
+
+            @Override
+            public void onSendAcknowledgement(Producer<?> producer, Message<?> message,
+                                              MessageId msgId, Throwable exception) {
+                // user-defined processing logic
+            }
         })
         .create();
    ```

client-libraries/websocket.md

@@ -81,6 +81,7 @@ All exchanges via the WebSocket API use JSON.
 ### Authentication
 
 #### Browser javascript WebSocket client
+> For security reasons, we suggest passing the token as headers rather than as query parameters.
 
 Use the query param `token` to transport the authentication token.
 

contribute/personal-ci.md

@@ -28,7 +28,8 @@ For example:
 ## CI workflows in a fork
 
 Before using personal CI workflows, ensure GitHub Actions is enabled for your fork in the GitHub UI. You can check this under your fork's "Settings" > "Actions" > "General" tab.
-Choose the "Allow all actions and reusable workflows" option.
+Choose the "Allow all actions and reusable workflows" option. 
+Note that some workflows, such as the required "Pulsar CI" and "Pulsar CI Flaky", may still be disabled by default and must be enabled explicitly. After enabling Actions for your forked repository, you can find these workflows in the "Actions" tab. To enable a workflow, select it from the left-hand sidebar and then click the "Enable workflow" button.
 
 Here are the steps to use your personal CI on GitHub:
 

data/release-java.js

@@ -1,10 +1,17 @@
 module.exports = [
+  {
+    "tagName": "v4.2.1",
+    "vtag": "4.2.x",
+    "releaseNotes": "/release-notes/versioned/client-java-4.2.1/",
+    "doc": "/docs/4.2.x/client-libraries-java",
+    "version": "v4.2.x"
+  },
   {
     "tagName": "v4.2.0",
     "vtag": "4.2.x",
     "releaseNotes": "/release-notes/versioned/client-java-4.2.0/",
     "doc": "/docs/4.2.x/client-libraries-java",
-    "version": "v4.2.x"
+    "version": ""
   },
   {
     "tagName": "v4.1.3",
@@ -34,12 +41,19 @@ module.exports = [
     "doc": "/docs/4.1.x/client-libraries-java",
     "version": ""
   },
+  {
+    "tagName": "v4.0.10",
+    "vtag": "4.0.x",
+    "releaseNotes": "/release-notes/versioned/client-java-4.0.10/",
+    "doc": "/docs/4.0.x/client-libraries-java",
+    "version": "v4.0.x"
+  },
   {
     "tagName": "v4.0.9",
     "vtag": "4.0.x",
     "releaseNotes": "/release-notes/versioned/client-java-4.0.9/",
     "doc": "/docs/4.0.x/client-libraries-java",
-    "version": "v4.0.x"
+    "version": ""
   },
   {
     "tagName": "v4.0.8",
@@ -237,12 +251,19 @@ module.exports = [
     "doc": "/docs/3.1.x/client-libraries-java",
     "version": ""
   },
+  {
+    "tagName": "v3.0.17",
+    "vtag": "3.0.x",
+    "releaseNotes": "/release-notes/versioned/client-java-3.0.17/",
+    "doc": "/docs/3.0.x/client-libraries-java",
+    "version": "v3.0.x"
+  },
   {
     "tagName": "v3.0.16",
     "vtag": "3.0.x",
     "releaseNotes": "/release-notes/versioned/client-java-3.0.16/",
     "doc": "/docs/3.0.x/client-libraries-java",
-    "version": "v3.0.x"
+    "version": ""
   },
   {
     "tagName": "v3.0.15",