DOCSEARCHbyAlgolia
Submit Docs

Apache Pulsar Node.js Client

repository·master·Indexed 41 days ago

https://github.com/apache/pulsar-client-node

A Node.js client library for Apache Pulsar (version 1.19.0-rc.0) that allows developers to create producers and consumers. It acts as a wrapper around the Pulsar C++ client using node-addon-api, providing support for ProtobufNativeSchema, various authentication mechanisms (Token, OAuth2, TLS, Athenz, Basic), and granular message acknowledgment and seek controls.

Tokens
5K
Snippets
25
Records
31
Agent score
51%

What's inside Apache Pulsar Node.js Client

  1. Run a Pulsar end-to-end example

    master

    This example demonstrates how to initialize a client, create a producer to send a message, and create a consumer to receive and acknowledge that message.

    Workflow:

    1. Initialize Pulsar.Client with a serviceUrl.
    2. Create a producer using client.createProducer() specifying a topic.
    3. Subscribe to a topic using client.subscribe() specifying a topic and subscription name.
    4. Send data using producer.send() with a Buffer.
    5. Receive data using consumer.receive().
    6. Acknowledge the message with consumer.acknowledge(msg).
    7. Close all resources: producer, consumer, and client.

    Note: This example assumes a Pulsar server is running at pulsar://localhost:6650.

    const Pulsar = require('pulsar-client');

(async () => {
  // Create a client
  const client = new Pulsar.Client({
    serviceUrl: 'pulsar://localhost:6650'
  });

  // Create a producer
  const producer = await client.createProducer({
    topic: 'persistent://public/default/my-topic',
  });

  // Create a consumer
  const consumer = await client.subscribe({
    topic: 'persistent://public/default/my-topic',
    subscription: 'sub1'
  });

  // Send a message
  producer.send({
    data: Buffer.from("hello")
  });

  // Receive the message
  const msg = await consumer.receive();
  console.log(msg.getData().toString());
  consumer.acknowledge(msg);

  await producer.close();
  await consumer.close();
  await client.close();
})();

  2. Create a Reader with Client.createReader()

    master

    Use createReader(params) to create a reader. Unlike a consumer, a reader is typically used for reading messages from a specific point in a topic without managing subscription state.

    const reader = await client.createReader({
  topic: 'my-topic',
  startMessageId: someMessageId,
});

  4. Get partitions for a topic

    master

    The GetPartitionsForTopic method allows you to retrieve the list of partitions associated with a specific topic. This is useful for managing partitioned topics.

    // Conceptual usage based on the C++ interface
const partitions = await client.getPartitionsForTopic('my-partitioned-topic');

  5. Subscribe to a topic

    master

    Use the Subscribe method on a Client instance to create a consumer for a specific topic. This allows you to receive messages from a Pulsar topic.

    // Conceptual usage based on the C++ interface
const consumer = await client.subscribe({ topic: 'my-topic', subscriptionName: 'my-sub' });

  6. Initialize the Pulsar client with Pulsar.Client

    master

    The Pulsar.Client class is the primary entry point for interacting with a Pulsar cluster. It is used to create producers, consumers, and other client-side resources. You can also configure authentication using the various authentication classes provided in the Pulsar namespace.

    const Pulsar = require('pulsar-client-node');

async function run() {
  const client = new Pulsar.Client({
    serviceUrl: 'pulsar://localhost:6650',
    // Authentication can be added here using Pulsar.AuthenticationToken, etc.
  });

  // Use client to create producers or consumers
  
  await client.close();
}

run();

  7. Generate a certificate file with Client.genCertFile()

    master

    The static method genCertFile() generates a cert.pem file in the current directory by aggregating the root certificates from the Node.js tls module. This is useful for setting up local TLS trust if you are relying on the default tlsTrustCertsFilePath.

    const Client = require('pulsar-client');

Client.genCertFile();

  8. Access Pulsar core types: Message, MessageId, and CryptoKeyReader

    master

    The Pulsar namespace exposes low-level types via PulsarBinding for handling message data and metadata:

    • Pulsar.Message: Represents a message received from a topic.
    • Pulsar.MessageId: Represents the unique identifier of a message.
    • Pulsar.CryptoKeyReader: Used for handling cryptographic keys.

  9. Initialize the Pulsar Client

    master

    The Client class is the primary entry point for interacting with Apache Pulsar. It is used to create producers, consumers (via Subscribe), and readers. In the Node.js environment, you instantiate it using the new Client(config) constructor, where config is an object containing connection details such as the service URL.

    // Conceptual usage based on the C++ interface
const { Client } = require('pulsar-client');
const client = new Client({ serviceUrl: 'pulsar://localhost:6650' });

  10. Configure logging with Client.setLogHandler()

    master

    The static method setLogHandler(params) allows you to configure how logs from the Pulsar client are handled. This is a static method and should be called on the Client class itself.

    const Client = require('pulsar-client');

Client.setLogHandler({
  // configuration parameters for the log handler
});

  11. Set a global log handler

    master

    You can intercept Pulsar client logs by calling SetLogHandler. This allows you to redirect internal Pulsar C++ logs to a Node.js callback function, enabling integration with Node.js logging frameworks.

    // Conceptual usage based on the C++ interface
const { Client } = require('pulsar-client');
Client.setLogHandler((logMessage) => {
  console.log(`[${logMessage.level}] ${logMessage.file}:${logMessage.line} - ${logMessage.message}`);
});

  12. Subscribe to a topic with Client.subscribe()

    master

    Use subscribe(params) to create a consumer that subscribes to a topic. The params object typically includes the topic and a subscriptionName.

    const consumer = await client.subscribe({
  topic: 'my-topic',
  subscription: 'my-subscription',
});