If Apache Iggy is useful to you, give it a star on GitHubStar apache/iggy
Skip to Content
Apache Iggy
SDKC++
These are the docs for Apache Iggy 0.10, kept for reference and no longer updated. Read the current docs.

C++ SDK

The C++ SDK, a CXX bridge over the Rust SDK, and how to build it from source with Bazel.

The Iggy C++ SDK wraps the Rust SDK through a CXX FFI bridge, so it can use all transport protocols (TCP, QUIC, HTTP, WebSocket) via connection strings. The source code is available at github.com/apache/iggy/tree/master/foreign/cpp.

This SDK isn't published to any package registry. Consume it from the monorepo and build it from source with Bazel.

Building from source

The project builds with the Bazel version pinned in .bazelversion (BUILD.bazel / MODULE.bazel). Its Rust bridge uses the Cargo and Rust toolchain provisioned by rules_rust, with a separate target directory in the Bazel output tree. Use a compatible Java runtime for Bazel. The pinned Bazel 9.2.0 requires Java 21 or newer.

cd foreign/cpp

# Build the library
bazel build //:iggy-cpp

# Unit tests
bazel test //:unit

# Low-level integration tests (require a running server)
bazel test //:e2e

Quick start

The snippet below mirrors the SDK's own end-to-end tests in foreign/cpp/tests/e2e. Start a local server on 127.0.0.1:8090 with the iggy/iggy credentials first. The stream name must not already exist.

#include "lib.rs.h"

#include <cstdint>
#include <iostream>
#include <string>
#include <utility>

iggy::ffi::Identifier id(const std::string &name) {
    iggy::ffi::Identifier identifier;
    identifier.set_string(name);
    return identifier;
}

iggy::ffi::Identifier numeric_id(const std::uint32_t value) {
    iggy::ffi::Identifier identifier;
    identifier.set_numeric(value);
    return identifier;
}

rust::Vec<std::uint8_t> payload(const std::string &text) {
    rust::Vec<std::uint8_t> bytes;
    for (const char c : text) {
        bytes.push_back(static_cast<std::uint8_t>(c));
    }
    return bytes;
}

int main() {
    iggy::ffi::Client *client = iggy::ffi::new_connection({});
    client->connect();
    iggy::ffi::ErrorInfo error_info{};
    client->login_user("iggy", "iggy", error_info);

    client->create_stream("my-stream", {}, error_info);

    iggy::ffi::TopicCreateOptions topic_options{};
    topic_options.has_partitions_count = true;
    topic_options.partitions_count = 1;
    client->create_topic(id("my-stream"), "my-topic", std::move(topic_options), error_info);

    rust::Vec<iggy::ffi::IggyMessageToSend> messages;
    for (int i = 0; i < 10; i++) {
        messages.push_back(iggy::ffi::make_message(
            payload("message-" + std::to_string(i)), {}));
    }
    client->send_messages(id("my-stream"), id("my-topic"), "balanced", {},
                          std::move(messages), error_info);

    iggy::ffi::PollOptions poll_options{};
    poll_options.count = 10;
    poll_options.min_count = 1;
    poll_options.max_bytes = 1024 * 1024;
    poll_options.commit = iggy::ffi::CommitPolicy::Manual;
    iggy::ffi::PollingStrategy strategy{};
    strategy.kind = "offset";
    strategy.value = 0;
    auto polled = client->poll_messages(id("my-stream"), id("my-topic"), 0,
                                        "consumer", numeric_id(1),
                                        std::move(strategy), poll_options, error_info);
    for (const auto &message : polled.messages) {
        std::string text(message.payload.begin(), message.payload.end());
        std::cout << "Offset: " << message.offset << ", Payload: " << text
                  << std::endl;
    }

    iggy::ffi::delete_client(client);
    return 0;
}

Polling strategies are selected by kind string: offset, timestamp, first, last, or next. Partitioning kinds for sending are balanced, partition_id, and messages_key.

Connection strings

The C++ SDK supports the same connection string format as the Rust SDK:

iggy://user:pass@host:port           (TCP, default)
iggy+quic://user:pass@host:port      (QUIC)
iggy+http://user:pass@host:port      (HTTP)
iggy+ws://user:pass@host:port        (WebSocket)

iggy::ffi::from_connection_string() accepts these strings. new_connection() instead takes an IggyClientConfig: {} selects TCP at 127.0.0.1:8090 without automatic login, and its server_address field overrides that address. Binary clients authenticate from their connection string during connect(). HTTP requires an explicit login_user() call. See connection strings for the supported options and credential syntax.

Helper types

Beyond the generated lib.rs.h FFI surface, foreign/cpp/include/iggy.hpp ships typed C++ helpers: CompressionAlgorithm, MaxTopicSize, Expiry, PollingStrategy, IdKind, TopicOption, SnapshotCompression, and SystemSnapshotType, plus the IggyException error type. They construct and validate the kind strings and values the raw FFI calls expect.

Current status

The FFI bridge exposes command-level operations for streams, topics, partitions, and segments. Message sending and polling with user headers. Consumer groups and consumer offsets. Stats, client info, and cluster metadata. Snapshots. User create/get/update/delete, permission updates and password changes. Topic option discovery (describe_options). And raw binary requests (send_binary_request).

The typed IggyBlockingClient also provides resource management, readers, consumers, offsets, user administration and client inspection. Personal access token creation is exposed by the bridge. Use iggy.hpp for typed StreamCreateOptions, TopicCreateOptions, update patches and PollOptions.

Readers and recovery

Reader reads batches from explicit partitions or a group assignment. StandaloneConsumer and GroupConsumer yield individual messages. Call Close before destruction. Manual commits are the default, and reader waits default to five seconds.

IggyException::OperationId() identifies retained uncertain operations. ResolveOperation retries a mutation with its retained identity, without returning the original payload. AbandonOperation frees local state without undoing the result. A lost committing poll reports fetch_progress_uncertain and blocks partition progress until abandonment.

The generated bridge passes ErrorInfo by reference to mutations, login, polls and recovery calls. Use a separate value for each concurrent call. GetMetadataChanges follows the metadata log, and send_binary_request_to_replica targets a node for supported non-replicated commands.

On this page