README.md

Iggy Examples

This directory contains comprehensive sample applications that showcase various usage patterns of the Iggy client SDK for Node.js, from basic operations to advanced scenarios. To learn more about building applications with Iggy, please refer to the getting started guide.

Running Examples

These examples target server 0.9.0 and use the SDK from the same checkout. Start the server from the repository root in a separate terminal:

cargo run --bin iggy-server -- --fresh --with-default-root-credentials

--fresh deletes existing local server data. Explicit credential environment variables override the default-root flag, and bootstrap settings do not replace recovered credentials. See the repository development prerequisites.

For server configuration options and help, from the repository root:

cargo run --bin iggy-server -- --help

You can also customize the server using environment variables:

# Enable HTTP transport and set the TCP address
IGGY_HTTP_ENABLED=true IGGY_TCP_ADDRESS=127.0.0.1:8090 \
  cargo run --bin iggy-server -- --fresh --with-default-root-credentials

From the repository root, build the local SDK before installing the examples:

npm --prefix foreign/node ci
npm --prefix foreign/node run build
npm --prefix examples/node ci
cd examples/node

Run the following scripts from examples/node. Set DEBUG=iggy:examples* to see progress. The separate producer and consumer scripts do not consistently share resources: envelope/header consumers create empty topics, and the tenant producer removes its streams before exiting. Getting-started/basic producers spread batches over five partitions while their consumers poll partition 0. The stream-builder example below is a self-contained send-and-consume walkthrough.

Basic Examples

Getting Started

Producer and consumer scripts:

npm run test:getting-started:producer
npm run test:getting-started:consumer

Basic Usage

Core functionality with detailed configuration options:

npm run test:basic:producer
npm run test:basic:consumer

Demonstrates fundamental client connection, authentication, batch message sending, and polling with support for TCP transport.

Message Envelope

Working with message envelopes:

npm run test:message-envelope:producer
npm run test:message-envelope:consumer

Demonstrates a JSON envelope containing message_type and a serialized payload.

Message Headers

Dispatching by a message type stored in the payload:

npm run test:message-headers:producer
npm run test:message-headers:consumer

This example stores messageType and data in a JSON payload wrapper.

Multi-Tenant

Multi-tenant application patterns:

npm run test:multi-tenant:producer
npm run test:multi-tenant:consumer

Each script uses one client with the supplied credentials to access separate tenant streams. Consumers poll with Consumer.Single.

Stream Builder

Creating a stream and topic, then sending and consuming messages:

npm run test:stream-builder

Uses the standard client API to send and consume three messages, then deletes the resources it created.

Sink Data Producer

Generating messages for sink connectors:

npm run test:sink-data-producer

Produces 100 batches of 100-499 JSON records. On completion it deletes the selected topic and stream, including resources that already existed.

TLS Examples

TCP/TLS

Producer and consumer examples using TLS-encrypted TCP connections with custom CA certificates:

npm run test:tcp-tls:producer
npm run test:tcp-tls:consumer

These examples require a TLS-enabled Iggy server. From the repository root:

IGGY_TCP_TLS_ENABLED=true \
IGGY_TCP_TLS_CERT_FILE=core/certs/iggy_cert.pem \
IGGY_TCP_TLS_KEY_FILE=core/certs/iggy_key.pem \
cargo run --bin iggy-server -- --fresh --with-default-root-credentials

The clients use transport: 'TLS', connect to localhost, and load ../../core/certs/iggy_ca_cert.pem relative to examples/node. These are repository development certificates.

Local checks

npm run test:unit
npm run lint