This directory contains comprehensive sample applications that showcase various usage patterns of the Iggy client SDK, from basic operations to advanced multi-tenant scenarios. To learn more about building applications with Iggy, please refer to the getting started guide.
Run all commands from the repository root, with the server in a separate terminal. For unreleased changes, use the SDK and server from the same checkout.
Iggy requires valid credentials to authenticate client requests. The examples assume that the server is using the default root credentials, which can be enabled in one of two ways:
Start the server with default credentials:
cargo run --bin iggy-server -- --with-default-root-credentials
Set the appropriate environment variables before starting the server with cargo run --bin iggy-server:
macOS/Linux:
export IGGY_ROOT_USERNAME=iggy export IGGY_ROOT_PASSWORD=iggy
Windows(Powershell):
$env:IGGY_ROOT_USERNAME = "iggy" $env:IGGY_ROOT_PASSWORD = "iggy"
Note
This setup is intended only for development and testing, not production use.
By default, all server data is stored in the local_data directory (this can be changed via system.path in config.toml).
Root credentials bootstrap a new state. Environment credentials override the default-credential flag; bootstrap settings do not replace recovered credentials. Once the server has created and populated the data directory, the existing stored credentials will always be used, and supplying the --with-default-root-credentials flag or setting the environment variables will no longer override them.
If the server has already been started once and your example returns Error: InvalidCredentials, then this means the stored credentials differ from the defaults.
You can reset the credentials in one of two ways:
Delete the existing data directory, then start the server again with the default-credential flag or environment variables.
Use the --fresh flag to force a reset:
cargo run --bin iggy-server -- --with-default-root-credentials --fresh
This deletes this replica's local data and re-initializes it. Use disposable development data. In a cluster, a fresh replica can recover credentials from peers; a new cluster requires explicit root credentials.
For server configuration options and help:
cargo run --bin iggy-server -- --help
You can also customize the server using environment variables:
## Example: Enable HTTP transport and set custom address IGGY_HTTP_ENABLED=true IGGY_HTTP_ADDRESS=127.0.0.1:3000 cargo run --bin iggy-server
You can run multiple producers and consumers simultaneously to observe how messages are distributed across clients. Most examples support configurable options via the Args struct, including transport protocol, stream/topic/partition settings, consumer ID, message size, and more.
Perfect introduction for newcomers to Iggy:
cargo run --example getting-started-producer cargo run --example getting-started-consumer
These examples use IggyClientBuilder with TCP transport and demonstrate stream/topic creation with basic message handling. Run the producer before the consumer on a fresh server: the consumer expects stream and topic IDs 0.
Core functionality with detailed configuration options:
cargo run --example basic-producer cargo run --example basic-consumer
Demonstrates fundamental client connection, authentication, batch message sending, and polling with support for TCP/QUIC/HTTP/WebSocket protocols.
To run the pair over HTTP:
cargo run --example basic-producer -- \ --transport http cargo run --example basic-consumer -- \ --transport http
Shows metadata management using custom headers:
cargo run --example message-headers-type-producer cargo run --example message-headers-type-consumer
Demonstrates using HeaderKey/HeaderValue for message metadata instead of payload-based typing, with header-based message routing.
Shows manual message compression using headers. This is the current workaround while built-in compression is unsupported:
cargo run --example message-headers-compression-producer cargo run --example message-headers-compression-consumer
Demonstrates typed header keys and values with various data types (strings, integers, floats, booleans, raw bytes):
cargo run --example typed-headers-producer cargo run --example typed-headers-consumer
JSON envelope pattern for polymorphic message handling:
cargo run --example message-envelope-producer cargo run --example message-envelope-consumer
Uses MessagesGenerator to create OrderCreated, OrderConfirmed, and OrderRejected messages wrapped in JSON envelopes for type identification.
Complex example demonstrating enterprise-level isolation:
cargo run --example multi-tenant-producer cargo run --example multi-tenant-consumer
Features multiple tenant setup, user creation with stream-specific permissions, concurrent producers/consumers across tenants, and security isolation. Configurable via environment variables (TENANTS_COUNT, PRODUCERS_COUNT, etc.).
Modern, ergonomic SDK usage patterns:
cargo run --example new-sdk-producer cargo run --example new-sdk-consumer
Showcases the newer SDK APIs with simplified setup, automatic topic creation, consumer groups, and AutoCommit configuration.
Testing and benchmarking support:
cargo run --example sink-data-producer
Produces 100 batches of 100 to 499 random user records, with a direct-send request limit of 1000 messages. Connection and stream settings are configurable via environment variables.
IggyStream abstraction for producer/consumer pairs:
cargo run --example stream-basic cargo run --example stream-producer cargo run --example stream-consumer
Comprehensive configuration examples with detailed documentation:
cargo run --example stream-producer-config cargo run --example stream-consumer-config
These examples document all available configuration options including partitioning strategies, retry policies, batching, AutoCommit strategies, polling strategies, and retry mechanisms.
Demonstrates secure TLS-encrypted TCP connections using custom CA certificates:
cargo run --example tcp-tls-producer cargo run --example tcp-tls-consumer
These examples require a TLS-enabled Iggy server. Start the server with:
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
Use the test certificates only for local development. The --fresh data-reset and credential qualifications above apply.
Uses IggyClientBuilder with TLS options (with_tls_enabled, with_tls_domain, with_tls_ca_file) to establish TLS-encrypted TCP connections with CA certificate verification.
All examples can be executed directly from the repository. Follow these steps:
cargo run --example EXAMPLE_NAMEMost examples use shared utilities from examples/rust/src/shared/ including:
The examples are automatically tested via scripts/run-examples-from-readme.sh --language rust to ensure they remain functional and up-to-date with the latest API changes.