Official Go client SDK for Apache Iggy message streaming.
The client speaks the VSR wire protocol over TCP, with or without TLS, in a blocking implementation. VSR is the only protocol it supports.
The current source requires Go 1.25 or newer. From your application module, install a release compatible with your server:
go get github.com/apache/iggy/foreign/go
Unversioned go get selects the latest stable release. VSR support starts with v0.9.0. For unreleased changes, build both SDK and server from the same checkout; examples/go/go.mod replaces this module with the local SDK source.
From the repository root, build and start a VSR server using a new, disposable data directory. The root environment variables bootstrap a new instance; they do not replace credentials recovered from disk or peers:
cargo build --bin iggy-server IGGY_PATH=/tmp/iggy-go \ IGGY_TCP_ADDRESS=127.0.0.1:8090 \ IGGY_HTTP_ENABLED=false IGGY_QUIC_ENABLED=false IGGY_WEBSOCKET_ENABLED=false \ IGGY_ROOT_USERNAME=iggy IGGY_ROOT_PASSWORD=iggy \ target/debug/iggy-server
QUIC, WebSocket and HTTP are enabled by default on ports 8080, 8092 and 3000. Disable the ones you do not need so they cannot race with another process.
SendMessages returns any placements the server reports. A send whose reply is lost to a dropped connection returns ErrDisconnected without a replay. A reconnect registers a new client identity, so a caller retry can append the batch twice. Consumers must handle duplicates through idempotent processing or application-level deduplication.
Crash durability follows the topic's durability policy: replicated confirms replication, while persisted also waits for the required replicas to persist the message data. An empty confirmation list is a valid success but does not by itself prove that new messages were appended.
In a cluster, auto-commit polls use persistent connections to partition primaries while the coordinator keeps the consumer's group membership. Servers must support primary poll routing and consumer-session attachment (binary commands 14, 103 and 104). Pause binary auto-commit consumers for the whole upgrade: upgrade every server first, then the SDKs, and restart consumers so they rejoin their groups. Older SDKs can lose membership when a backup refuses an offset commit; the new SDK does not fall back to legacy polling. Only a poll refused before admission is retried. ErrTransientNotCommitted or cancellation after sending a poll can mean its offset advanced without a reply; the SDK does not replay that poll automatically.
Unit tests need nothing running:
go test ./...
The end-to-end suite runs against a server at the address in IGGY_TCP_ADDRESS and skips when that variable is unset:
IGGY_TCP_ADDRESS=127.0.0.1:8090 go test ./tests
Add IGGY_TCP_TLS_ENABLED=true to run the TLS cases against a server started with IGGY_TCP_TLS_ENABLED=true and the certificate pair in core/certs.
From the repository root, the integration harness builds a three-node fixture, seeds messages, moves metadata leadership independently of the partition primary, and runs the Go regression. It requires Go on PATH:
cargo build --bin iggy-server --bin iggy cargo test -p integration given_split_primaries_when_go_group_auto_commits_should_preserve_membership -- --ignored
To use an existing fixture, set its coordinator address and topic. The test expects eight messages per partition by default; override that with the positive integer IGGY_POLL_ROUTING_MESSAGES_PER_PARTITION when needed:
IGGY_TCP_ADDRESS=127.0.0.1:20016 \ IGGY_POLL_ROUTING_STREAM=sdk-primary-routing \ IGGY_POLL_ROUTING_TOPIC=go \ go test ./tests -run TestE2E_SplitPrimaryPollsPreserveCoordinatorMembership
Before creating a pull request, please run golangci-lint and fix any reported lint issues:
golangci-lint run